Add NetBox plugin - #137

🔌 Plugin overview

• Plugin name: NetBox
• Purpose / problem solved: Brings a NetBox network source of truth into SquaredUp: device and site inventory, IP prefix and VLAN capacity, rack space and unit-by-unit rack elevations, power feeds, data-quality gaps, lifecycle and circuits, and the change log.
  • It recreates the NetBox views a customer (WSP) runs today in Grafana, including power feed → rack → site, racks per site, rack space utilization, rack elevation and a map of data centres.
  • It indexes Sites, Racks, Devices, Virtual Machines, Prefixes and Circuits, so NetBox's intended inventory sits alongside monitoring data. Device and VM objects carry their name and primary IP for that comparison.
• Primary audience: Network and data centre teams who use NetBox as their source of truth, and the managers who need inventory and capacity views without using the NetBox UI.
• Authentication method(s): NetBox API token.
  • Supports v2 tokens (NetBox 4.5+, sent as Authorization: Bearer nbt_<key>.<secret>) and legacy v1 tokens (Authorization: Token <token>), with a deprecation notice when v1 is selected.
  • The token can be pasted exactly as NetBox displays it, with or without the leading Bearer. The header is built in a small pre-request script.
  • A read-only token is enough.
  • Optional Ignore certificate errors for self-managed instances with self-signed certificates. It's wired into the base config (TeamDynamix, Kubernetes and Proxmox VE are missing that wiring).

Works with NetBox Community, Enterprise and Cloud, which all expose the same REST and GraphQL APIs. Uses REST for lists and counts, and GraphQL where REST would need several calls: power feeds with their rack and site, rack utilization, and rack elevation.

🖼️ Plugin screenshots

Plugin configuration

Data source configuration:

Default dashboards

Screenshots are from testing against the public NetBox demo instance (https://demo.netbox.dev), not customer data.

Overview:

IPAM Capacity:

Rack Capacity:

Data Quality:

Lifecycle and Circuits:

Change Activity:

Data Centers:

Power:

Device Inventory:

Site:

Rack:

Device:

Virtual Machine:

Prefix:

Circuit:

🧪 Test plan

Tested end to end against a live, authenticated NetBox 4.7.2 (the public demo at https://demo.netbox.dev), from SquaredUp Prod and Dev organizations. This was not just validation.

Authentication and connectivity

• Both token formats: data sources authenticated in Prod with a v2 token and with a v1 token. configValidation passes both steps: the status endpoint, then site read access.
• URL handling: a trailing / or /api on the NetBox URL is normalized.
• Dev: authentication was re-verified after moving header construction into the pre-request script. The newer platform build in Dev no longer evaluates JavaScript over secret fields in base headers.

Import

• Full import in Prod and Dev, with all six steps succeeding. The Dev run indexed 48 Sites, 51 Racks, 180 Devices, 182 Virtual Machines, 96 Prefixes and 30 Circuits.
• Object properties were checked on imported objects, including the primary IP stored without its mask.

Data streams

• Every stream, live: all 17 streams were tested with the CLI against the live instance, comparing row counts with the NetBox API count.
• Paging: offset paging needed base: 0. Without it, every list silently dropped its first row.
• GraphQL paging: GraphQL lists are hard-capped at 1,000 rows, so the GraphQL streams page through a GraphQL $offset variable.
• Prefix Utilization: hand-checked against raw API counts, covering VRF and global active prefixes, and global and VRF containers with nested children merged. IPv6, pool and "mark utilized" cases were checked offline.
• Rack Elevation: hand-checked unit by unit against NetBox's own elevation for both faces, with 0 mismatches on three racks. That covers multi-U devices, half-U positions and racks numbered top-down.
• Filters: Rack Utilization, Power Feeds and all optional filters (Site, Rack, Role, Prefix, Device, Virtual machine, Assignment, Status, change log Object/Action/Type) were checked against two different objects each.

Dashboards

• All 15 render in Dev without tile errors. Every SmartViz vizSpec was checked with validate_visualization, and every tile keeps a classic visualisation as fallback.
• Geo Map: the Data Centers Site Map was verified in Dev with real coordinates loaded on the demo sites. It needs the SmartViz Geo Map from SAAS-10095, which reaches Prod on October 8; until then the tile shows its Sites table.

Still to do before merge: re-verify v1 and v2 authentication in Prod after the pre-request script change.

⚠️ Known limitations

Documented in full in the plugin README. The significant ones:

• Prefix utilization makes one request per prefix.
  • NetBox has no utilization or IP-count field in REST or GraphQL, and GraphQL can't count past 1,000.
  • The IPAM Capacity dashboard keeps it to a single tile.
  • IP ranges marked as populated aren't counted.
• GraphQL lists stop at 1,000 items. The plugin's GraphQL streams page automatically. Queries in the generic GraphQL Query stream must add pagination themselves.
• Rack space is counted on either face. 0U devices and devices in device bays are listed separately in Rack Elevation.
• Power is rated capacity, not live draw. NetBox doesn't store live draw. Custom fields (e.g. a measured kVA %) appear as columns.
• The site map needs coordinates. Sites need latitude and longitude set in NetBox, because NetBox doesn't geocode addresses.
• Large inventories. Lists of many thousands of devices or IP addresses should use the stream filters to stay within the response size limit.
• Data sources must be re-saved after connection changes. A plugin update that changes the base connection settings only takes effect for an existing data source once it's saved again.

Related platform issues found while building this are being raised separately: multi-value scalar layout, rack elevation visualization, object-only dashboard variables, and vizSpec validation in the plugin CLI.

📚 Checklist

• This PR adds a single plugin only
• Plugin, datastream and UI naming follow SquaredUp guidelines
• Logo added
• One or more dashboards added
• README added including configuration guidance
• No secrets or credentials included
• I agree to the Code of Conduct

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added NetBox integration for monitoring sites, racks, devices, virtual machines, IP addresses, prefixes, circuits, and power feeds.
  • Added dashboards for capacity, inventory, data quality, change activity, and lifecycle tracking, plus perspectives for individual NetBox objects.
  • Added GraphQL query support and options to filter and explore NetBox data.
  • Added connection setup for v1 and v2 API tokens, with URL and certificate settings.

• Documentation

  • Added setup guidance, supported features, and known limitations.